<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
	<title>6.270 - JoyOS: lib/pid.h File Reference</title>
	<link href="main.css" media="screen" rel="Stylesheet" type="text/css"/>
	<link href="doxygen.css" rel="stylesheet" type="text/css">
</head>  
<body>
	<div id="header">
		<div id="headerb">
		<div id="headtext">
			<span class="titletext">AUTONOMOUS ROBOT DESIGN COMPETITION</span>
			6.270
		</div>
		<div class="mainmenu">
			<a href="http://web.mit.edu/6.270/www">Home</a>
		 	&bull;
			<a href="http://web.mit.edu/6.270/www/about/">About</a> 
		 	&bull;
			<a href="http://web.mit.edu/6.270/www/sponsors/">Sponsors</a>
		 	&bull;
			<a href="http://web.mit.edu/6.270/www/contests/">Past Contests</a> 
		 	&bull;
			<a href="http://web.mit.edu/6.270/www/contestants/">Contestant Information</a>
		</div>
	</div>
	</div>

<div class="maincontent">
<!-- Generated by Doxygen 1.5.6 -->
<div class="navigation" id="top">
  <div class="tabs">
    <ul>
      <li><a href="index.html"><span>Main&nbsp;Page</span></a></li>
      <li><a href="annotated.html"><span>Data&nbsp;Structures</span></a></li>
      <li class="current"><a href="files.html"><span>Files</span></a></li>
    </ul>
  </div>
</div>
<div class="contents">
<h1>lib/pid.h File Reference</h1>Generic PID (Proportional Integral Derivative) controller implementation. <a href="#_details">More...</a>
<p>
<code>#include &lt;<a class="el" href="global_8h.html">kern/global.h</a>&gt;</code><br>
<table border="0" cellpadding="0" cellspacing="0">
<tr><td></td></tr>
<tr><td colspan="2"><br><h2>Data Structures</h2></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">struct &nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="structpid__controller.html">pid_controller</a></td></tr>

<tr><td colspan="2"><br><h2>Functions</h2></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">void&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="pid_8h.html#8c0b6255d6f0e3b0eb9f6a5190f98585">init_pid</a> (struct <a class="el" href="structpid__controller.html">pid_controller</a> *pid, float kp, float ki, float kd, float(*input)(), void(*output)(float value))</td></tr>

<tr><td class="memItemLeft" nowrap align="right" valign="top">float&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="pid_8h.html#5cfae1fb524e684323188e38e992a907">update_pid_input</a> (struct <a class="el" href="structpid__controller.html">pid_controller</a> *pid, float current_val)</td></tr>

<tr><td class="memItemLeft" nowrap align="right" valign="top">float&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="pid_8h.html#27760f7e62fe94c9904eaf9a2d78657d">update_pid</a> (struct <a class="el" href="structpid__controller.html">pid_controller</a> *pid)</td></tr>

<tr><td class="memItemLeft" nowrap align="right" valign="top">uint8_t&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="pid_8h.html#6d26e3243ea00af007b69ee2c75b076f">dispatch_pid</a> (struct <a class="el" href="structpid__controller.html">pid_controller</a> *pid, float tolerance, uint8_t(*stop)())</td></tr>

</table>
<hr><a name="_details"></a><h2>Detailed Description</h2>
A PID is a commonly used feedback mechanism used to correct error between a measured process variable and a desired setpoint.<p>
A Common use in robotics (especially in 6.270) is the position control of a motor. In this case the process variable is the wheels angular position, and the setpoint is a desired target position (eg: 720 degrees, or two wheel rotations forward). The wheel position is measured with shaft encoders and the motor is commanded by the PID controller to compensate for the error between the current wheel position and the desired goal.<p>
This allows the user to command a desired amount of wheel rotation (and hence distance travelled). With a PID controller on each wheel the user can perform reasonably accurate motions (straight lines, in place turns, etc).<p>
For more information see <a href="http://en.wikipedia.org/wiki/PID_controller">http://en.wikipedia.org/wiki/PID_controller</a> <hr><h2>Function Documentation</h2>
<a class="anchor" name="6d26e3243ea00af007b69ee2c75b076f"></a><!-- doxytag: member="pid.h::dispatch_pid" ref="6d26e3243ea00af007b69ee2c75b076f" args="(struct pid_controller *pid, float tolerance, uint8_t(*stop)())" -->
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">uint8_t dispatch_pid           </td>
          <td>(</td>
          <td class="paramtype">struct <a class="el" href="structpid__controller.html">pid_controller</a> *&nbsp;</td>
          <td class="paramname"> <em>pid</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">float&nbsp;</td>
          <td class="paramname"> <em>tolerance</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">uint8_t(*)()&nbsp;</td>
          <td class="paramname"> <em>stop</em></td><td>&nbsp;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td><td></td>
        </tr>
      </table>
</div>
<div class="memdoc">

<p>
Dispatch to a routine that will drive the PID system until the output equals the goal within tolerance. This routine blocks and only returns when done or 'stop' is non-zero and returns non-zero.<p>
<dl compact><dt><b>Parameters:</b></dt><dd>
  <table border="0" cellspacing="2" cellpadding="0">
    <tr><td valign="top"></td><td valign="top"><em>pid</em>&nbsp;</td><td>PID controller </td></tr>
    <tr><td valign="top"></td><td valign="top"><em>tolerance</em>&nbsp;</td><td>how close to get towards the goal </td></tr>
    <tr><td valign="top"></td><td valign="top"><em>stop</em>&nbsp;</td><td>return when stop() is true </td></tr>
  </table>
</dl>

</div>
</div><p>
<a class="anchor" name="8c0b6255d6f0e3b0eb9f6a5190f98585"></a><!-- doxytag: member="pid.h::init_pid" ref="8c0b6255d6f0e3b0eb9f6a5190f98585" args="(struct pid_controller *pid, float kp, float ki, float kd, float(*input)(), void(*output)(float value))" -->
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">void init_pid           </td>
          <td>(</td>
          <td class="paramtype">struct <a class="el" href="structpid__controller.html">pid_controller</a> *&nbsp;</td>
          <td class="paramname"> <em>pid</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">float&nbsp;</td>
          <td class="paramname"> <em>kp</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">float&nbsp;</td>
          <td class="paramname"> <em>ki</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">float&nbsp;</td>
          <td class="paramname"> <em>kd</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">float(*)()&nbsp;</td>
          <td class="paramname"> <em>input</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">void(*)(float value)&nbsp;</td>
          <td class="paramname"> <em>output</em></td><td>&nbsp;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td><td></td>
        </tr>
      </table>
</div>
<div class="memdoc">

<p>
Initialize a PID controller structure. This function takes an empty <a class="el" href="structpid__controller.html">pid_controller</a> structure and initializes its member variables.<p>
<dl compact><dt><b>Parameters:</b></dt><dd>
  <table border="0" cellspacing="2" cellpadding="0">
    <tr><td valign="top"></td><td valign="top"><em>pid</em>&nbsp;</td><td>empty PID to initialize </td></tr>
    <tr><td valign="top"></td><td valign="top"><em>kp</em>&nbsp;</td><td>proportional constant </td></tr>
    <tr><td valign="top"></td><td valign="top"><em>ki</em>&nbsp;</td><td>integral constant </td></tr>
    <tr><td valign="top"></td><td valign="top"><em>kd</em>&nbsp;</td><td>derivative constant </td></tr>
    <tr><td valign="top"></td><td valign="top"><em>input</em>&nbsp;</td><td>input function </td></tr>
    <tr><td valign="top"></td><td valign="top"><em>output</em>&nbsp;</td><td>output function </td></tr>
  </table>
</dl>

</div>
</div><p>
<a class="anchor" name="27760f7e62fe94c9904eaf9a2d78657d"></a><!-- doxytag: member="pid.h::update_pid" ref="27760f7e62fe94c9904eaf9a2d78657d" args="(struct pid_controller *pid)" -->
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">float update_pid           </td>
          <td>(</td>
          <td class="paramtype">struct <a class="el" href="structpid__controller.html">pid_controller</a> *&nbsp;</td>
          <td class="paramname"> <em>pid</em>          </td>
          <td>&nbsp;)&nbsp;</td>
          <td></td>
        </tr>
      </table>
</div>
<div class="memdoc">

<p>
Perform a single step of the PID loop. The <a class="el" href="pid_8h.html#27760f7e62fe94c9904eaf9a2d78657d">update_pid()</a> steps are as follows:<p>
<ul>
<li>check the pid is enabled</li><li>call pid-&gt;input() and store the result in current</li><li>calculate error (pid-&gt;goal - current)</li><li>calculate P, I, D components and sum result</li><li>call pid-&gt;output() with result</li></ul>
<p>
<dl compact><dt><b>Parameters:</b></dt><dd>
  <table border="0" cellspacing="2" cellpadding="0">
    <tr><td valign="top"></td><td valign="top"><em>pid</em>&nbsp;</td><td>PID controller </td></tr>
  </table>
</dl>

</div>
</div><p>
<a class="anchor" name="5cfae1fb524e684323188e38e992a907"></a><!-- doxytag: member="pid.h::update_pid_input" ref="5cfae1fb524e684323188e38e992a907" args="(struct pid_controller *pid, float current_val)" -->
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">float update_pid_input           </td>
          <td>(</td>
          <td class="paramtype">struct <a class="el" href="structpid__controller.html">pid_controller</a> *&nbsp;</td>
          <td class="paramname"> <em>pid</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">float&nbsp;</td>
          <td class="paramname"> <em>current_val</em></td><td>&nbsp;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td><td></td>
        </tr>
      </table>
</div>
<div class="memdoc">

<p>
Perform a single step of the PID loop. like <a class="el" href="pid_8h.html#27760f7e62fe94c9904eaf9a2d78657d">update_pid()</a> except takes a current value as an argument<p>
<dl compact><dt><b>Parameters:</b></dt><dd>
  <table border="0" cellspacing="2" cellpadding="0">
    <tr><td valign="top"></td><td valign="top"><em>pid</em>&nbsp;</td><td>PID controller </td></tr>
    <tr><td valign="top"></td><td valign="top"><em>current_val</em>&nbsp;</td><td>Current control value </td></tr>
  </table>
</dl>

</div>
</div><p>
</div>
</div>
<div class="maincontent">
	<div class="footer centre">
		<hr>
		Generated on Sun Jan 18 22:59:34 2009 by&nbsp;<a href="http://www.doxygen.org/index.html">Doxygen</a> 1.5.6<br/>
		6.270 Staff, 2008 | 
		<a href="mailto:6.270-organizers@mit.edu">Contact Us</a> | 
		<a href="http://web.mit.edu">MIT</a>
	</div>
</div>
</body>
</html>
